<!DOCTYPE html>
<html lang="en" data-color-mode="auto" data-light-theme="light" data-dark-theme="dark">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>G4F - Client API Guide</title>
    <link rel="apple-touch-icon" sizes="180x180" href="/dist/img/apple-touch-icon.png">
    <link rel="icon" type="image/png" sizes="32x32" href="/dist/img/favicon-32x32.png">
    <link rel="icon" type="image/png" sizes="16x16" href="/dist/img/favicon-16x16.png">
    <link rel="manifest" href="/dist/img/site.webmanifest">
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/light-74231a1f3bbb.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/dark-8a995f0bacd4.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/primer-primitives-225433424a87.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/primer-b8b91660c29d.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/global-205098e9fedd.css" />
    <link crossorigin="anonymous" media="all" rel="stylesheet" href="https://github.githubassets.com/assets/code-177d21388df8.css" />
    <style>
        :root {
            --colour-1: #000000;
            --colour-2: #ccc;
            --colour-3: #e4d4ff;
            --colour-4: #f0f0f0;
            --colour-5: #181818;
            --colour-6: #242424;
            --accent: #8b3dff;
            --gradient: #1a1a1a;
            --background: #16101b;
            --size: 70vw;
            --top: 50%;
            --blur: 40px;
            --opacity: 0.6;
        }

        /* Body and text color */
        body {
            height: 100vh;
            margin: 0;
            padding: 0;
        }

        .hidden {
            display: none;
        }

        .container-lg {
            margin: 0 auto;
            padding: 8px;
        }

        @media only screen and (min-width: 40em) {
            .container-lg {
                max-width: 84%;
            }
        }
    </style>
</head>
<body>
    <article class="markdown-body entry-content container-lg" itemprop="text"><div class="markdown-heading"><h2 class="heading-element">G4F - Client API Guide</h2><a id="user-content-g4f---client-api-guide" class="anchor" aria-label="Permalink: G4F - Client API Guide" href="#g4f---client-api-guide"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="markdown-heading"><h2 class="heading-element">Table of Contents</h2><a id="user-content-table-of-contents" class="anchor" aria-label="Permalink: Table of Contents" href="#table-of-contents"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#getting-started">Getting Started</a></li>
<li><a href="#switching-to-g4f-client">Switching to G4F Client</a></li>
<li><a href="#initializing-the-client">Initializing the Client</a></li>
<li><a href="#creating-chat-completions">Creating Chat Completions</a></li>
<li><a href="#configuration">Configuration</a></li>
<li><a href="#explanation-of-parameters">Explanation of Parameters</a></li>
<li><a href="#usage-examples">Usage Examples</a></li>
<li><a href="#text-completions">Text Completions</a></li>
<li><a href="#streaming-completions">Streaming Completions</a></li>
<li><a href="#using-a-vision-model">Using a Vision Model</a></li>
<li><a href="#image-generation">Image Generation</a></li>
<li><a href="#creating-image-variations">Creating Image Variations</a></li>
<li><a href="#advanced-usage">Advanced Usage</a></li>
<li><a href="#conversation-memory">Conversation Memory</a></li>
<li><a href="#search-tool-support">Search Tool Support</a></li>
<li><a href="#using-a-list-of-providers-with-retryprovider">Using a List of Providers with RetryProvider</a></li>
<li><a href="#using-a-vision-model">Using a Vision Model</a></li>
<li><a href="#command-line-chat-program">Command-line Chat Program</a></li>
</ul>
<div class="markdown-heading"><h2 class="heading-element">Introduction</h2><a id="user-content-introduction" class="anchor" aria-label="Permalink: Introduction" href="#introduction"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>Welcome to the G4F Client API, a cutting-edge tool for seamlessly integrating advanced AI capabilities into your Python applications. This guide is designed to facilitate your transition from using the OpenAI client to the G4F Client, offering enhanced features while maintaining compatibility with the existing OpenAI API.</p>
<hr>
<div class="markdown-heading"><h2 class="heading-element">Getting Started</h2><a id="user-content-getting-started" class="anchor" aria-label="Permalink: Getting Started" href="#getting-started"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="markdown-heading"><h3 class="heading-element">Switching to G4F Client</h3><a id="user-content-switching-to-g4f-client" class="anchor" aria-label="Permalink: Switching to G4F Client" href="#switching-to-g4f-client"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>To begin using the G4F Client, simply update your import statement in your Python code:</strong></p>
<p><strong>Old Import:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">openai</span> <span class="pl-k">import</span> <span class="pl-v">OpenAI</span></pre></div>
<p><strong>New Import:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span> <span class="pl-k">as</span> <span class="pl-v">OpenAI</span></pre></div>
<p>The G4F Client preserves the same familiar API interface as OpenAI, ensuring a smooth transition process.</p>
<hr>
<div class="markdown-heading"><h2 class="heading-element">Initializing the Client</h2><a id="user-content-initializing-the-client" class="anchor" aria-label="Permalink: Initializing the Client" href="#initializing-the-client"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>To utilize the G4F Client, create a new instance. <strong>Below is an example showcasing custom providers:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>
<span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-v">Provider</span> <span class="pl-k">import</span> <span class="pl-v">BingCreateImages</span>, <span class="pl-v">OpenaiChat</span>, <span class="pl-v">Gemini</span>

<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>(
    <span class="pl-s1">provider</span><span class="pl-c1">=</span><span class="pl-v">OpenaiChat</span>,
    <span class="pl-s1">image_provider</span><span class="pl-c1">=</span><span class="pl-v">Gemini</span>,
    <span class="pl-c"># Add any other necessary parameters</span>
)</pre></div>
<hr>
<div class="markdown-heading"><h2 class="heading-element">Creating Chat Completions</h2><a id="user-content-creating-chat-completions" class="anchor" aria-label="Permalink: Creating Chat Completions" href="#creating-chat-completions"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>Here’s an improved example of creating chat completions:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">chat</span>.<span class="pl-c1">completions</span>.<span class="pl-c1">create</span>(
    <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s">"gpt-4o-mini"</span>,
    <span class="pl-s1">messages</span><span class="pl-c1">=</span>[
        {
            <span class="pl-s">"role"</span>: <span class="pl-s">"user"</span>,
            <span class="pl-s">"content"</span>: <span class="pl-s">"Say this is a test"</span>
        }
    ]
    <span class="pl-c"># Add any other necessary parameters</span>
)</pre></div>
<p><strong>This example:</strong></p>
<ul>
<li>Asks a specific question <code>Say this is a test</code>
</li>
<li>Configures various parameters like temperature and max_tokens for more control over the output</li>
<li>Disables streaming for a complete response</li>
</ul>
<p>You can adjust these parameters based on your specific needs.</p>
<div class="markdown-heading"><h2 class="heading-element">Configuration</h2><a id="user-content-configuration" class="anchor" aria-label="Permalink: Configuration" href="#configuration"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>You can set an <code>api_key</code> for your provider in the client and define a proxy for all outgoing requests:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>

<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>(
    <span class="pl-s1">api_key</span><span class="pl-c1">=</span><span class="pl-s">"your_api_key_here"</span>,
    <span class="pl-s1">proxies</span><span class="pl-c1">=</span><span class="pl-s">"http://user:pass@host"</span>,
    <span class="pl-c"># Add any other necessary parameters</span>
)</pre></div>
<hr>
<div class="markdown-heading"><h2 class="heading-element">Explanation of Parameters</h2><a id="user-content-explanation-of-parameters" class="anchor" aria-label="Permalink: Explanation of Parameters" href="#explanation-of-parameters"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>When using the G4F to create chat completions or perform related tasks, you can configure the following parameters:</strong></p>
<ul>
<li>
<p><strong><code>model</code></strong>:<br>
Specifies the AI model to be used for the task. Examples include <code>"gpt-4o"</code> for GPT-4 Optimized or <code>"gpt-4o-mini"</code> for a lightweight version. The choice of model determines the quality and speed of the response. Always ensure the selected model is supported by the provider.</p>
</li>
<li>
<p><strong><code>messages</code></strong>:<br>
<strong>A list of dictionaries representing the conversation context. Each dictionary contains two keys:</strong>
- <code>role</code>: Defines the role of the message sender, such as <code>"user"</code> (input from the user) or <code>"system"</code> (instructions to the AI).<br>
- <code>content</code>: The actual text of the message.<br>
<strong>Example:</strong></p>
<div class="highlight highlight-source-python"><pre>[
    {<span class="pl-s">"role"</span>: <span class="pl-s">"system"</span>, <span class="pl-s">"content"</span>: <span class="pl-s">"You are a helpful assistant."</span>},
    {<span class="pl-s">"role"</span>: <span class="pl-s">"user"</span>, <span class="pl-s">"content"</span>: <span class="pl-s">"What day is it today?"</span>}
]</pre></div>
</li>
<li>
<p><strong><code>provider</code></strong>:
<em>(Optional)</em> Specifies the backend provider for the API. Examples include <code>g4f.Provider.Blackbox</code> or <code>g4f.Provider.OpenaiChat</code>. Each provider may support a different subset of models and features, so select one that matches your requirements.</p>
</li>
<li>
<p><strong><code>web_search</code></strong> (Optional):<br>
Boolean flag indicating whether to enable internet-based search capabilities. This is useful for obtaining real-time or specific details not included in the model’s training data.</p>
</li>
</ul>
<div class="markdown-heading"><h4 class="heading-element">Providers Limitation</h4><a id="user-content-providers-limitation" class="anchor" aria-label="Permalink: Providers Limitation" href="#providers-limitation"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>The <code>web_search</code> argument is <strong>limited to specific providers</strong>, including:</p>
<ul>
<li>ChatGPT</li>
<li>HuggingChat</li>
<li>Blackbox</li>
<li>RubiksAI</li>
</ul>
<p>If your chosen provider does not support <code>web_search</code>, it will not function as expected.</p>
<p><strong>Alternative Solution:</strong><br>
Instead of relying on the <code>web_search</code> argument, you can use the more versatile <strong>Search Tool Support</strong>, which allows for highly customizable web search operations. The search tool enables you to define parameters such as query, number of results, word limit, and timeout, offering greater control over search capabilities.</p>
<hr>
<div class="markdown-heading"><h2 class="heading-element">Usage Examples</h2><a id="user-content-usage-examples" class="anchor" aria-label="Permalink: Usage Examples" href="#usage-examples"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="markdown-heading"><h3 class="heading-element">Text Completions</h3><a id="user-content-text-completions" class="anchor" aria-label="Permalink: Text Completions" href="#text-completions"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>Generate text completions using the <code>ChatCompletions</code> endpoint:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>

<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>()

<span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">chat</span>.<span class="pl-c1">completions</span>.<span class="pl-c1">create</span>(
    <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s">"gpt-4o-mini"</span>,
    <span class="pl-s1">messages</span><span class="pl-c1">=</span>[
        {
            <span class="pl-s">"role"</span>: <span class="pl-s">"user"</span>,
            <span class="pl-s">"content"</span>: <span class="pl-s">"Say this is a test"</span>
        }
    ],
    <span class="pl-s1">web_search</span> <span class="pl-c1">=</span> <span class="pl-c1">False</span>
)

<span class="pl-en">print</span>(<span class="pl-s1">response</span>.<span class="pl-c1">choices</span>[<span class="pl-c1">0</span>].<span class="pl-c1">message</span>.<span class="pl-c1">content</span>)</pre></div>
<div class="markdown-heading"><h3 class="heading-element">Streaming Completions</h3><a id="user-content-streaming-completions" class="anchor" aria-label="Permalink: Streaming Completions" href="#streaming-completions"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>Process responses incrementally as they are generated:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>

<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>()

<span class="pl-s1">stream</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">chat</span>.<span class="pl-c1">completions</span>.<span class="pl-c1">create</span>(
    <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s">"gpt-4"</span>,
    <span class="pl-s1">messages</span><span class="pl-c1">=</span>[
        {
            <span class="pl-s">"role"</span>: <span class="pl-s">"user"</span>,
            <span class="pl-s">"content"</span>: <span class="pl-s">"Say this is a test"</span>
        }
    ],
    <span class="pl-s1">stream</span><span class="pl-c1">=</span><span class="pl-c1">True</span>,
    <span class="pl-s1">web_search</span> <span class="pl-c1">=</span> <span class="pl-c1">False</span>
)

<span class="pl-k">for</span> <span class="pl-s1">chunk</span> <span class="pl-c1">in</span> <span class="pl-s1">stream</span>:
    <span class="pl-k">if</span> <span class="pl-s1">chunk</span>.<span class="pl-c1">choices</span>[<span class="pl-c1">0</span>].<span class="pl-c1">delta</span>.<span class="pl-c1">content</span>:
        <span class="pl-en">print</span>(<span class="pl-s1">chunk</span>.<span class="pl-c1">choices</span>[<span class="pl-c1">0</span>].<span class="pl-c1">delta</span>.<span class="pl-c1">content</span> <span class="pl-c1">or</span> <span class="pl-s">""</span>, <span class="pl-s1">end</span><span class="pl-c1">=</span><span class="pl-s">""</span>)</pre></div>
<hr>
<div class="markdown-heading"><h3 class="heading-element">Using a Vision Model</h3><a id="user-content-using-a-vision-model" class="anchor" aria-label="Permalink: Using a Vision Model" href="#using-a-vision-model"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>Analyze an image and generate a description:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">import</span> <span class="pl-s1">g4f</span>
<span class="pl-k">import</span> <span class="pl-s1">requests</span>

<span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>
<span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-v">Provider</span>.<span class="pl-v">GeminiPro</span> <span class="pl-k">import</span> <span class="pl-v">GeminiPro</span>

<span class="pl-c"># Initialize the GPT client with the desired provider and api key</span>
<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>(
    <span class="pl-s1">api_key</span><span class="pl-c1">=</span><span class="pl-s">"your_api_key_here"</span>,
    <span class="pl-s1">provider</span><span class="pl-c1">=</span><span class="pl-v">GeminiPro</span>
)

<span class="pl-s1">image</span> <span class="pl-c1">=</span> <span class="pl-s1">requests</span>.<span class="pl-c1">get</span>(<span class="pl-s">"https://raw.githubusercontent.com/xtekky/gpt4free/refs/heads/main/docs/images/cat.jpeg"</span>, <span class="pl-s1">stream</span><span class="pl-c1">=</span><span class="pl-c1">True</span>).<span class="pl-c1">raw</span>
<span class="pl-c"># Or: image = open("docs/images/cat.jpeg", "rb")</span>

<span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">chat</span>.<span class="pl-c1">completions</span>.<span class="pl-c1">create</span>(
    <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s1">g4f</span>.<span class="pl-c1">models</span>.<span class="pl-c1">default</span>,
    <span class="pl-s1">messages</span><span class="pl-c1">=</span>[
        {
            <span class="pl-s">"role"</span>: <span class="pl-s">"user"</span>,
            <span class="pl-s">"content"</span>: <span class="pl-s">"What's in this image?"</span>
        }
    ],
    <span class="pl-s1">image</span><span class="pl-c1">=</span><span class="pl-s1">image</span>
    <span class="pl-c"># Add any other necessary parameters</span>
)

<span class="pl-en">print</span>(<span class="pl-s1">response</span>.<span class="pl-c1">choices</span>[<span class="pl-c1">0</span>].<span class="pl-c1">message</span>.<span class="pl-c1">content</span>)</pre></div>
<hr>
<div class="markdown-heading"><h3 class="heading-element">Image Generation</h3><a id="user-content-image-generation" class="anchor" aria-label="Permalink: Image Generation" href="#image-generation"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>The <code>response_format</code> parameter is optional and can have the following values:</strong></p>
<ul>
<li>
<strong>If not specified (default):</strong> The image will be saved locally, and a local path will be returned (e.g., "/images/1733331238_cf9d6aa9-f606-4fea-ba4b-f06576cba309.jpg").</li>
<li>
<strong>"url":</strong> Returns a URL to the generated image.</li>
<li>
<strong>"b64_json":</strong> Returns the image as a base64-encoded JSON string.</li>
</ul>
<p><strong>Generate images using a specified prompt:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>

<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>()

<span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">images</span>.<span class="pl-c1">generate</span>(
    <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s">"flux"</span>,
    <span class="pl-s1">prompt</span><span class="pl-c1">=</span><span class="pl-s">"a white siamese cat"</span>,
    <span class="pl-s1">response_format</span><span class="pl-c1">=</span><span class="pl-s">"url"</span>
    <span class="pl-c"># Add any other necessary parameters</span>
)

<span class="pl-s1">image_url</span> <span class="pl-c1">=</span> <span class="pl-s1">response</span>.<span class="pl-c1">data</span>[<span class="pl-c1">0</span>].<span class="pl-c1">url</span>

<span class="pl-en">print</span>(<span class="pl-s">f"Generated image URL: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">image_url</span><span class="pl-kos">}</span></span>"</span>)</pre></div>
<div class="markdown-heading"><h4 class="heading-element">Base64 Response Format</h4><a id="user-content-base64-response-format" class="anchor" aria-label="Permalink: Base64 Response Format" href="#base64-response-format"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>

<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>()

<span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">images</span>.<span class="pl-c1">generate</span>(
    <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s">"flux"</span>,
    <span class="pl-s1">prompt</span><span class="pl-c1">=</span><span class="pl-s">"a white siamese cat"</span>,
    <span class="pl-s1">response_format</span><span class="pl-c1">=</span><span class="pl-s">"b64_json"</span>
    <span class="pl-c"># Add any other necessary parameters</span>
)

<span class="pl-s1">base64_text</span> <span class="pl-c1">=</span> <span class="pl-s1">response</span>.<span class="pl-c1">data</span>[<span class="pl-c1">0</span>].<span class="pl-c1">b64_json</span>
<span class="pl-en">print</span>(<span class="pl-s1">base64_text</span>)</pre></div>
<div class="markdown-heading"><h3 class="heading-element">Creating Image Variations</h3><a id="user-content-creating-image-variations" class="anchor" aria-label="Permalink: Creating Image Variations" href="#creating-image-variations"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>Create variations of an existing image:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>
<span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-v">Provider</span> <span class="pl-k">import</span> <span class="pl-v">OpenaiChat</span>

<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>(
    <span class="pl-s1">image_provider</span><span class="pl-c1">=</span><span class="pl-v">OpenaiChat</span>
)

<span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">images</span>.<span class="pl-c1">create_variation</span>(
    <span class="pl-s1">image</span><span class="pl-c1">=</span><span class="pl-en">open</span>(<span class="pl-s">"docs/images/cat.jpg"</span>, <span class="pl-s">"rb"</span>),
    <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s">"dall-e-3"</span>,
    <span class="pl-c"># Add any other necessary parameters</span>
)

<span class="pl-s1">image_url</span> <span class="pl-c1">=</span> <span class="pl-s1">response</span>.<span class="pl-c1">data</span>[<span class="pl-c1">0</span>].<span class="pl-c1">url</span>

<span class="pl-en">print</span>(<span class="pl-s">f"Generated image URL: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">image_url</span><span class="pl-kos">}</span></span>"</span>)</pre></div>
<hr>
<div class="markdown-heading"><h2 class="heading-element">Advanced Usage</h2><a id="user-content-advanced-usage" class="anchor" aria-label="Permalink: Advanced Usage" href="#advanced-usage"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="markdown-heading"><h3 class="heading-element">Conversation Memory</h3><a id="user-content-conversation-memory" class="anchor" aria-label="Permalink: Conversation Memory" href="#conversation-memory"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>To maintain a coherent conversation, it's important to store the context or history of the dialogue. This can be achieved by appending both the user's inputs and the bot's responses to a messages list. This allows the model to reference past exchanges when generating responses.</p>
<p><strong>The conversation history consists of messages with different roles:</strong></p>
<ul>
<li>
<code>system</code>: Initial instructions that define the AI's behavior</li>
<li>
<code>user</code>: Messages from the user</li>
<li>
<code>assistant</code>: Responses from the AI</li>
</ul>
<p><strong>The following example demonstrates how to implement conversation memory with the G4F:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>

<span class="pl-k">class</span> <span class="pl-v">Conversation</span>:
    <span class="pl-k">def</span> <span class="pl-en">__init__</span>(<span class="pl-s1">self</span>):
        <span class="pl-s1">self</span>.<span class="pl-c1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>()
        <span class="pl-s1">self</span>.<span class="pl-c1">history</span> <span class="pl-c1">=</span> [
            {
                <span class="pl-s">"role"</span>: <span class="pl-s">"system"</span>,
                <span class="pl-s">"content"</span>: <span class="pl-s">"You are a helpful assistant."</span>
            }
        ]
    
    <span class="pl-k">def</span> <span class="pl-en">add_message</span>(<span class="pl-s1">self</span>, <span class="pl-s1">role</span>, <span class="pl-s1">content</span>):
        <span class="pl-s1">self</span>.<span class="pl-c1">history</span>.<span class="pl-c1">append</span>({
            <span class="pl-s">"role"</span>: <span class="pl-s1">role</span>,
            <span class="pl-s">"content"</span>: <span class="pl-s1">content</span>
        })
    
    <span class="pl-k">def</span> <span class="pl-en">get_response</span>(<span class="pl-s1">self</span>, <span class="pl-s1">user_message</span>):
        <span class="pl-c"># Add user message to history</span>
        <span class="pl-s1">self</span>.<span class="pl-c1">add_message</span>(<span class="pl-s">"user"</span>, <span class="pl-s1">user_message</span>)
        
        <span class="pl-c"># Get response from AI</span>
        <span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">self</span>.<span class="pl-c1">client</span>.<span class="pl-c1">chat</span>.<span class="pl-c1">completions</span>.<span class="pl-c1">create</span>(
            <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s">"gpt-4o-mini"</span>,
            <span class="pl-s1">messages</span><span class="pl-c1">=</span><span class="pl-s1">self</span>.<span class="pl-c1">history</span>,
            <span class="pl-s1">web_search</span><span class="pl-c1">=</span><span class="pl-c1">False</span>
        )
        
        <span class="pl-c"># Add AI response to history</span>
        <span class="pl-s1">assistant_response</span> <span class="pl-c1">=</span> <span class="pl-s1">response</span>.<span class="pl-c1">choices</span>[<span class="pl-c1">0</span>].<span class="pl-c1">message</span>.<span class="pl-c1">content</span>
        <span class="pl-s1">self</span>.<span class="pl-c1">add_message</span>(<span class="pl-s">"assistant"</span>, <span class="pl-s1">assistant_response</span>)
        
        <span class="pl-k">return</span> <span class="pl-s1">assistant_response</span>

<span class="pl-k">def</span> <span class="pl-en">main</span>():
    <span class="pl-s1">conversation</span> <span class="pl-c1">=</span> <span class="pl-en">Conversation</span>()
    
    <span class="pl-en">print</span>(<span class="pl-s">"="</span> <span class="pl-c1">*</span> <span class="pl-c1">50</span>)
    <span class="pl-en">print</span>(<span class="pl-s">"G4F Chat started (type 'exit' to end)"</span>.<span class="pl-c1">center</span>(<span class="pl-c1">50</span>))
    <span class="pl-en">print</span>(<span class="pl-s">"="</span> <span class="pl-c1">*</span> <span class="pl-c1">50</span>)
    <span class="pl-en">print</span>(<span class="pl-s">"<span class="pl-cce">\n</span>AI: Hello! How can I assist you today?"</span>)
    
    <span class="pl-k">while</span> <span class="pl-c1">True</span>:
        <span class="pl-s1">user_input</span> <span class="pl-c1">=</span> <span class="pl-en">input</span>(<span class="pl-s">"<span class="pl-cce">\n</span>You: "</span>)
        
        <span class="pl-k">if</span> <span class="pl-s1">user_input</span>.<span class="pl-c1">lower</span>() <span class="pl-c1">==</span> <span class="pl-s">'exit'</span>:
            <span class="pl-en">print</span>(<span class="pl-s">"<span class="pl-cce">\n</span>Goodbye!"</span>)
            <span class="pl-k">break</span>
            
        <span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">conversation</span>.<span class="pl-c1">get_response</span>(<span class="pl-s1">user_input</span>)
        <span class="pl-en">print</span>(<span class="pl-s">"<span class="pl-cce">\n</span>AI:"</span>, <span class="pl-s1">response</span>)

<span class="pl-k">if</span> <span class="pl-s1">__name__</span> <span class="pl-c1">==</span> <span class="pl-s">"__main__"</span>:
    <span class="pl-en">main</span>()</pre></div>
<p><strong>Key Features:</strong></p>
<ul>
<li>Maintains conversation context through a message history</li>
<li>Includes system instructions for AI behavior</li>
<li>Automatically stores both user inputs and AI responses</li>
<li>Simple and clean implementation using a class-based approach</li>
</ul>
<p><strong>Usage Example:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-s1">conversation</span> <span class="pl-c1">=</span> <span class="pl-en">Conversation</span>()
<span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">conversation</span>.<span class="pl-c1">get_response</span>(<span class="pl-s">"Hello, how are you?"</span>)
<span class="pl-en">print</span>(<span class="pl-s1">response</span>)</pre></div>
<p><strong>Note:</strong>
The conversation history grows with each interaction. For long conversations, you might want to implement a method to limit the history size or clear old messages to manage token usage.</p>
<hr>
<div class="markdown-heading"><h2 class="heading-element">Search Tool Support</h2><a id="user-content-search-tool-support" class="anchor" aria-label="Permalink: Search Tool Support" href="#search-tool-support"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p>The <strong>Search Tool Support</strong> feature enables triggering a web search during chat completions. This is useful for retrieving real-time or specific data, offering a more flexible solution than <code>web_search</code>.</p>
<p><strong>Example Usage</strong>:</p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>

<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>()

<span class="pl-s1">tool_calls</span> <span class="pl-c1">=</span> [
    {
        <span class="pl-s">"function"</span>: {
            <span class="pl-s">"arguments"</span>: {
                <span class="pl-s">"query"</span>: <span class="pl-s">"Latest advancements in AI"</span>,
                <span class="pl-s">"max_results"</span>: <span class="pl-c1">5</span>,
                <span class="pl-s">"max_words"</span>: <span class="pl-c1">2500</span>,
                <span class="pl-s">"backend"</span>: <span class="pl-s">"auto"</span>,
                <span class="pl-s">"add_text"</span>: <span class="pl-c1">True</span>,
                <span class="pl-s">"timeout"</span>: <span class="pl-c1">5</span>
            },
            <span class="pl-s">"name"</span>: <span class="pl-s">"search_tool"</span>
        },
        <span class="pl-s">"type"</span>: <span class="pl-s">"function"</span>
    }
]

<span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">chat</span>.<span class="pl-c1">completions</span>.<span class="pl-c1">create</span>(
    <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s">"gpt-4"</span>,
    <span class="pl-s1">messages</span><span class="pl-c1">=</span>[
        {<span class="pl-s">"role"</span>: <span class="pl-s">"user"</span>, <span class="pl-s">"content"</span>: <span class="pl-s">"Tell me about recent advancements in AI."</span>}
    ],
    <span class="pl-s1">tool_calls</span><span class="pl-c1">=</span><span class="pl-s1">tool_calls</span>
)

<span class="pl-en">print</span>(<span class="pl-s1">response</span>.<span class="pl-c1">choices</span>[<span class="pl-c1">0</span>].<span class="pl-c1">message</span>.<span class="pl-c1">content</span>)</pre></div>
<p><strong>Parameters for <code>search_tool</code>:</strong></p>
<ul>
<li>
<strong><code>query</code></strong>: The search query string.</li>
<li>
<strong><code>max_results</code></strong>: Number of search results to retrieve.</li>
<li>
<strong><code>max_words</code></strong>: Maximum number of words in the response.</li>
<li>
<strong><code>backend</code></strong>: The backend used for search (e.g., <code>"api"</code>).</li>
<li>
<strong><code>add_text</code></strong>: Whether to include text snippets in the response.</li>
<li>
<strong><code>timeout</code></strong>: Maximum time (in seconds) for the search operation.</li>
</ul>
<p><strong>Advantages of Search Tool Support:</strong></p>
<ul>
<li>Works with any provider, irrespective of <code>web_search</code> support.</li>
<li>Offers more customization and control over the search process.</li>
<li>Bypasses provider-specific limitations.</li>
</ul>
<hr>
<div class="markdown-heading"><h3 class="heading-element">Using a List of Providers with RetryProvider</h3><a id="user-content-using-a-list-of-providers-with-retryprovider" class="anchor" aria-label="Permalink: Using a List of Providers with RetryProvider" href="#using-a-list-of-providers-with-retryprovider"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<div class="highlight highlight-source-python"><pre><span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>
<span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-v">Provider</span> <span class="pl-k">import</span> <span class="pl-v">RetryProvider</span>, <span class="pl-v">Phind</span>, <span class="pl-v">FreeChatgpt</span>, <span class="pl-v">Liaobots</span>
<span class="pl-k">import</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">debug</span>

<span class="pl-s1">g4f</span>.<span class="pl-c1">debug</span>.<span class="pl-c1">logging</span> <span class="pl-c1">=</span> <span class="pl-c1">True</span>
<span class="pl-s1">g4f</span>.<span class="pl-c1">debug</span>.<span class="pl-c1">version_check</span> <span class="pl-c1">=</span> <span class="pl-c1">False</span>

<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>(
    <span class="pl-s1">provider</span><span class="pl-c1">=</span><span class="pl-en">RetryProvider</span>([<span class="pl-v">Phind</span>, <span class="pl-v">FreeChatgpt</span>, <span class="pl-v">Liaobots</span>], <span class="pl-s1">shuffle</span><span class="pl-c1">=</span><span class="pl-c1">False</span>)
)

<span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">chat</span>.<span class="pl-c1">completions</span>.<span class="pl-c1">create</span>(
    <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s">""</span>,
    <span class="pl-s1">messages</span><span class="pl-c1">=</span>[
        {
            <span class="pl-s">"role"</span>: <span class="pl-s">"user"</span>,
            <span class="pl-s">"content"</span>: <span class="pl-s">"Hello"</span>
        }
    ]
)

<span class="pl-en">print</span>(<span class="pl-s1">response</span>.<span class="pl-c1">choices</span>[<span class="pl-c1">0</span>].<span class="pl-c1">message</span>.<span class="pl-c1">content</span>)</pre></div>
<div class="markdown-heading"><h2 class="heading-element">Command-line Chat Program</h2><a id="user-content-command-line-chat-program" class="anchor" aria-label="Permalink: Command-line Chat Program" href="#command-line-chat-program"><span aria-hidden="true" class="octicon octicon-link"></span></a></div>
<p><strong>Here's an example of a simple command-line chat program using the G4F Client:</strong></p>
<div class="highlight highlight-source-python"><pre><span class="pl-k">import</span> <span class="pl-s1">g4f</span>
<span class="pl-k">from</span> <span class="pl-s1">g4f</span>.<span class="pl-s1">client</span> <span class="pl-k">import</span> <span class="pl-v">Client</span>

<span class="pl-c"># Initialize the GPT client with the desired provider</span>
<span class="pl-s1">client</span> <span class="pl-c1">=</span> <span class="pl-en">Client</span>()

<span class="pl-c"># Initialize an empty conversation history</span>
<span class="pl-s1">messages</span> <span class="pl-c1">=</span> []

<span class="pl-k">while</span> <span class="pl-c1">True</span>:
    <span class="pl-c"># Get user input</span>
    <span class="pl-s1">user_input</span> <span class="pl-c1">=</span> <span class="pl-en">input</span>(<span class="pl-s">"You: "</span>)

    <span class="pl-c"># Check if the user wants to exit the chat</span>
    <span class="pl-k">if</span> <span class="pl-s1">user_input</span>.<span class="pl-c1">lower</span>() <span class="pl-c1">==</span> <span class="pl-s">"exit"</span>:
        <span class="pl-en">print</span>(<span class="pl-s">"Exiting chat..."</span>)
        <span class="pl-k">break</span>  <span class="pl-c"># Exit the loop to end the conversation</span>

    <span class="pl-c"># Update the conversation history with the user's message</span>
    <span class="pl-s1">messages</span>.<span class="pl-c1">append</span>({<span class="pl-s">"role"</span>: <span class="pl-s">"user"</span>, <span class="pl-s">"content"</span>: <span class="pl-s1">user_input</span>})

    <span class="pl-k">try</span>:
        <span class="pl-c"># Get GPT's response</span>
        <span class="pl-s1">response</span> <span class="pl-c1">=</span> <span class="pl-s1">client</span>.<span class="pl-c1">chat</span>.<span class="pl-c1">completions</span>.<span class="pl-c1">create</span>(
            <span class="pl-s1">messages</span><span class="pl-c1">=</span><span class="pl-s1">messages</span>,
            <span class="pl-s1">model</span><span class="pl-c1">=</span><span class="pl-s1">g4f</span>.<span class="pl-c1">models</span>.<span class="pl-c1">default</span>,
        )

        <span class="pl-c"># Extract the GPT response and print it</span>
        <span class="pl-s1">gpt_response</span> <span class="pl-c1">=</span> <span class="pl-s1">response</span>.<span class="pl-c1">choices</span>[<span class="pl-c1">0</span>].<span class="pl-c1">message</span>.<span class="pl-c1">content</span>
        <span class="pl-en">print</span>(<span class="pl-s">f"Bot: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">gpt_response</span><span class="pl-kos">}</span></span>"</span>)

        <span class="pl-c"># Update the conversation history with GPT's response</span>
        <span class="pl-s1">messages</span>.<span class="pl-c1">append</span>({<span class="pl-s">"role"</span>: <span class="pl-s">"assistant"</span>, <span class="pl-s">"content"</span>: <span class="pl-s1">gpt_response</span>})

    <span class="pl-k">except</span> <span class="pl-v">Exception</span> <span class="pl-k">as</span> <span class="pl-s1">e</span>:
        <span class="pl-en">print</span>(<span class="pl-s">f"An error occurred: <span class="pl-s1"><span class="pl-kos">{</span><span class="pl-s1">e</span><span class="pl-kos">}</span></span>"</span>)</pre></div>
<p>This guide provides a comprehensive overview of the G4F Client API, demonstrating its versatility in handling various AI tasks, from text generation to image analysis and creation. By leveraging these features, you can build powerful and responsive applications that harness the capabilities of advanced AI models.</p>
<hr>
<p><a href="/docs/">Return to Documentation</a></p>
</article>
</body>
</html>